#####################################################################
# Product:      KnowledgeEngine (Plone Edition)
#
# File:         Datum.py
#
# Copyright:    Copyright (c) 2005, Faulkner Technologies
#
# Author:       Brian Oliver
#
# Description:  This file defines a simple data element
#               that is graphable.  For example: a bar in a barchart.
#
#               Instances of this class are usually managed by Graphable(s)
#
#               NOTE: This class is not persistent and does not
#               actually render graphs
#
# See Also:     Graphable
#####################################################################

#####################################################################
## Zope Library Imports
from Globals import InitializeClass
from AccessControl import ClassSecurityInfo
from AccessControl.Role import RoleManager
from DateTime import DateTime
 
#####################################################################
## Python Library Imports
import os

#####################################################################
## Datum Class Definition
class Datum(RoleManager):
    """
        A lazily in-memory storage-agnostic representation of 
        Graphable information.
    """
        
    #---------------------------------------------------------------#

    #declare security so ClassInfo may be accessed in DTML/ZPT etc
    security = ClassSecurityInfo()
    security.declareObjectPublic()
    security.setDefaultAccess("allow")

    #---------------------------------------------------------------#

    def __init__(self, identity = None, title="", value="", color="black", description = "", url = "", tooltip = "", footnote = "", callout = "", context = {}):
        """
            Default constructor for a Datum
            
            PARAMETERS:
            identity            The unique identity of the datum in a graphable.
                                (If None, an identity will be allocated when added to a Graphable)
            title               The title for the datum
            value               The numeric value of the datum
            description         (Optional) Additional description of the datum
            url                 (Optional) URL to visit when the datum is selected
            tooltip             (Optional) The tooltip to display on datum rollover
            footnote            (Optional) A footnote for this datum to be displayed as required by the graphable
            callout             (Optional) A short fragment of text to display in the graphable for the datum.
            context             (Optional) A dictionary of addition information for the datum.  
                                May be used to provide context to the datum generation or further processing
        """
        
        self.identity = identity
        self.title = title
        self.value = value
        self.color = color
        self.description = description
        self.url = url
        self.tooltip = tooltip
        self.footnote = footnote
        self.callout = callout
        self.context = context
        
    #---------------------------------------------------------------#
 
    def clone(self):
        """
            (Deep) Clone and return a new instance.
            
            (the new instance will not have an identity)
        """
        
        return Datum(title=self.title, value=self.value, color=self.color, description=self.description, url=self.url, tooltip=self.tooltip, footnote=self.footnote, context=self.context)
        
    #---------------------------------------------------------------#
 
    def getIdentity(self):
        """
            Return the unique identity of the datum when
            placed in a Graphable
        """
        
        return self.identity
        
    #---------------------------------------------------------------#
 
    def setIdentity(self, identity):
        """
            Set the unique identity for the datum when placed in a 
            Graphable
        """
        
        self.identity = identity
        
    #---------------------------------------------------------------#

    def getTitle(self):
        """
            Return the title for the Datum
        """
        
        return self.title
        
    #---------------------------------------------------------------#

    def getValue(self):
        """
            Return the value for the Datum
        """
        
        return self.value
        
    #---------------------------------------------------------------#

    def getColor(self):
        """
            Return the color for the Datum
        """
        
        return self.color
        
    #---------------------------------------------------------------#

    def hasFootnote(self):
        """
            Return if the datum has a footnote
        """
        
        return len(self.footnote) > 0
        
    #---------------------------------------------------------------#

    def getFootnote(self):
        """
            Return the footnote for the Datum
        """
        
        return self.footnote
        
    #---------------------------------------------------------------#

    def setFootnote(self, footnote):
        """
            Set the footnote for the Datum
        """
        
        self.footnote = footnote
        
    #---------------------------------------------------------------#

    def getCallout(self):
        """
            Return the callout for the Datum
        """
        
        return self.callout
        
    #---------------------------------------------------------------#

    def getContext(self):
        """
            Return the context dictionary for the Datum
        """
        
        return self.context
 
    #---------------------------------------------------------------#
        
#####################################################################
## Class Initialisation
InitializeClass(Datum)
